Inside Macintosh: AppleScript Scripting Additions Guide /

Chapter 1 - Introduction to Scripting Additions

Installing Scripting Additions

When you install AppleScript using the Installer as described in Getting Started With AppleScript, the Installer creates a folder in the Extensions folder (which is located inside the System Folder for your computer) called Scripting Additions and copies a number of scripting addition files into that folder. The file type of a scripting addition (displayed in the Get Info window) is "AppleScript document."

Figure 1-1 shows a scripting addition icon. For a list of the scripting additions installed with AppleScript and the commands they provide, see Table 2-1: Scripting Additions Commands.

Figure 1-1 A scripting addition icon

Each scripting addition file contains one or more command handlers. If a scripting addition file is located in the Scripting Additions folder (in the Extensions folder of the System Folder), the command handlers it provides are available for use by any script whose target is an application on that computer.

Some scripting additions also define object classes for records returned by their commands. However, scripting addition commands do not normally act on objects defined by individual applications.

The scripting addition commands Activate, Log, Start Log, and Stop Log are part of the AppleScript extension and do not have separate files in the Scripting Additions folder. With the exception of these commands, AppleScript recognizes scripting addition commands only if the corresponding scripting addition files are located in the Scripting Additions folder. If after installing AppleScript you receive additional scripting additions from Apple or another vendor, you must copy them into the Scripting Additions folder before you can use their commands in scripts.

If you use a scripting addition command in a script and get an error message stating that the command is undefined, check to make sure the corresponding scripting addition is installed in the Scripting Additions folder.

Sending Scripting Addition Commands

Like the target of an application command, the target of a scripting addition command is always an application object or a script object. If the script doesn't explicitly specify the target with a Tell statement, AppleScript sends the command to the default target application, which is usually the application running the script (for example, the Script Editor).

A scripting addition command performs its action only after the command has been received by a target application. Unlike application commands, scripting addition commands always work the same way regardless of the application to which they are sent.

For example, the scripting addition command Display Dialog displays a dialog box that can include text, one or more buttons, an icon, and a field in which the user can type text. In the script that follows, the target of the Display Dialog command is the Scriptable Text Editor application. When the script runs, the Scriptable Text Editor becomes the frontmost application (that is, its menus become visible and its windows become the frontmost windows on the screen) and passes the command to the scripting addition's handler for the Display Dialog command, which displays the dialog box.

tell application "Scriptable Text Editor"   display dialog "What's your name?" default answer ""end tell

In the next example, the Display Dialog command is not enclosed in a Tell statement, nor does it have a direct parameter, so its target is the Script Editor (or whatever application runs the script). When you run the script, the Script Editor passes the command to the scripting addition's handler for the Display Dialog command, which displays the dialog box in the Script Editor's layer (that is, in front of any other Script Editor windows that may be open) while the Script Editor is still the active application.

set theCount to number of words in front document of ÿ   app "Scriptable Text Editor"if theCount > 500 then
   display dialog "You have exceeded your word limit."end

You can send scripting addition commands to a target on any remote computer whose Scripting Additions folder contains the appropriate scripting addition file. This is true no matter which scripting additions are available to the computer from which you are sending the command. For example, you can send the Display Dialog command to any application on a remote computer whose Scripting Additions folder contains the Display Dialog scripting addition, even if the Scripting Additions folder on your computer doesn't contain that file.

Each scripting addition that contains command handlers has its own dictionary, which lists the reserved words--including the command names, parameter labels, and in some cases object names--used to invoke the commands supported by the scripting addition. If a scripting addition dictionary includes words that are also part of an application dictionary, then you cannot use those words within Tell statements to that application.

For example, the Offset command provided by the String Commands scripting addition reports the offset, in characters, of a string within another string. Offset is also a property of several Scriptable Text Editor objects and is thus a word in the Scriptable Text Editor dictionary. Therefore, you cannot use Offset as a scripting addition command within Tell statements to the Scriptable Text Editor. If you do, you'll get a syntax error, because the Scriptable Text Editor treats the word Offset as a property of a text object.

If you specify a script object as the target of a scripting addition command, the script object either handles the command itself (potentially modifying it) or uses a Continue statement to pass the command to the default target application. For more information about scripting addition commands, script objects, and the Continue statement, see Chapter 9, "Script Objects," of the AppleScript Language Guide.

---

Subtopics

Sending Scripting Addition Commands